'\" t
'
' Name:		tplist.1m
'
' Completed:	13th August, 2003.
'
' Updated:	9th August, 2004.
'
' Purpose:	Describes the tplist command.
'
' Author:	Simon Edwards, Proprius Consulting Ltd.
'
' Version:	@(#)1.1 Original (SE)
' 		@(#)1.2 New format details
'
.TH tplist 1M "9 August 2004" "Linuxha.net"

.SH NAME
tplist - List packages installed or available in depot

.SH SYNOPSIS
.TS
l.
tplist \fB-d\fP \fIdepot\fP [\fB-p\fP \fIpkg\fP] [\fB-l\fP] [\fB-v\fP] [\fB-o\fP \fIpkg|files|bundle\fP]
       - List packages or bundles in a depot

tplist [\fB-p\fP \fIpkg\fP] [\fB-l\fP] [\fB-v\fP] [\fB-o\fP \fIpkg|files|bundle\fP]
       - List installed packages or bundles

.TE

.SH DESCRIPTION

The \fitplist(1M)\fP utility is used to list packages or bundles that are 
either installed or are located in a named depot. The terms "package", "bundle",
"installed" and "depot" and more information on the "Tarp" package format 
can be found in the \fItpintro(1M)\fP manual page.

The utility supports normal, long and file-level outputs (though the current
argument handling is probably not as logical as it might be).

.SH OPERATING MODES
As shown in the \fBSYNOPSIS\fP section the utility works in two different 
manners. This short section describes the differences between the two.

.SS Listing Installed Software
In the form given to list information from the currently installed software,
the installed package database information is taken from the directory /var/adm/tarp. However it is possible to override this directory by setting the
environment variable \fBTARP_DB\fP. This facility is typically used to allow
ordinary users to have personal software installations.

.SS Listing Software from a Depot
When listing software from a depot the options are identical, though some of
the fields generated are different, (see the examples section below for
further details).

Currently listing details of the software packages in a depot can be quite
slow, (relative to listing installed software), since depots do not currently
have an index facility to speed searching up.

.SH BUNDLE HANDLING
The default mode of listing is "per-package", however in this mode, if 
the depot being examined (or installed software), then the packages from
each depot are also shown. If you wish to show information on just bundled
software then the "-o bundle" option should be used (as explained below).

.SH ARGUMENTS
Due to the simplistic nature of this packaging software the number of 
options currently available to control details of listing packages is limited.
It is likely these will be supplemented in the future as demand dictates.

All arguments are optional unless otherwise stated.
.TP 4
.B -d
Mandatory argument if you wish to list information from a depot. The argument
is followed by the name of the depot in question. When this argument is not
specified then the output will be taken from the packages in the installed
package database.

If a depot name is specified it should be currently a full path - for
example use "-d $PWD" if the current directory is a depot.

A depot does not need to contain only "Tarp" packages or bundles - other
files in the specified directory are silently ignored.
.TP
.B -p
The package to show details for - this can include a wildcard, so "tools_*"
would match "tool_shed", "tool_box" etc. Remember to put the argument in
quotes if you do use wild cards to ensure no shell globbing occurs.

If no \fB-p\fP option is specified then all packages in the depot or 
installed will be shown.
.TP
.B -v
Verbose mode - shows progress messages as the script executes. In the current
version of the script this adds nothing to the standard output.
.TP
.B -l
Produce a long listing of details of all matching packages. Without this
option just a single line of output would be shown. For example of the normal 
and long output modes please see the \fBEXAMPLES\fP section below.
.TP
.B -o
Specifies whether the output should be package of file based - the default is
"pkg" - use "file" to show file level details of the package. When "-o file" 
is used the \fB-l\fP option is ignored.

Outputing file level details will show each of the files that are installed, 
(or would be installed in the case of depot software). When listing this level
of details from an installed package the paths given need to be prefixed 
by the root directory used during the package installation - this is shown
at the start of the listing below the file name.

The "bundle" level simply lists at a very high level - just a single line 
for each bundle giving the name, description and number of packages
contained or installed.

.SH EXAMPLES
The first example simply lists all products that are installed in a
users installed package database defined as "/home/sedwards/tarpdb":

.TS
l.
$ TARP_DB=$HOME/tarp; export TARP_DB
$ tplist
.TE

In this case the output generated will be in the following format:

.TS
l.
Bundle     : fred
Version    : 1.2.0
Description: Simon test bundle description

Package              Version    Status     Description
==================== ========== ========== ===================================
dummy2               1.0.0      Committed  dummy application2
pre1                 1.0.0      Committed  dummy application3

Non-bundled packages...

Package              Version    Status     Description
==================== ========== ========== =============================
functions            1.02.00    Committed  generic functions 
healthcheck          1.01.00    Committed  Healthcheck utility 
.TE

Notice that the details of bundled software installed are shown
before packages that were not installed as part of a bundle.

The next example shows the packages currently available in the depot
"/tmp/sdepot" - again in short format:

.TS
l.
$ tplist -d /tmp/sdepot
.TE

In this case the output would look similar to the following:

.TS
l.
Packages bundled...

Bundle     : testbundle
Version    : 1.2.0
Description: Simon test bundle description

Package              Version    OS         Arch       Description
==================== ========== ========== ========== ========================
MBNA_dummy           1.0.0      HP-UX      9000800    dummy application 
MBNA_dummy2          1.0.0      HP-UX      9000800    dummy application2

Packages not bundled...

Package              Version    OS         Arch       Description
==================== ========== ========== ========== ========================
pre1                 1.0.0      HP-UX      9000800    dummy application3
.TE

Notice that although it is only possible to install a single version of a 
package, (in the same installed package database), the depot can contain
multiple versions of the same package.

The next example shows one of the current limitations of this tool - it is
not possible to pick just a single version of the same package from a 
depot. The command below shows the long listing format of the
package "healthcheck" from the depot "/tmp/sdepot":

.TS
l.
$ tplist -p healthcheck -l -d /tmp/sdepot
.TE

This will generate the following output:

.TS
l.
healthcheck:
        Version: 1.00.00
        Description: Healthcheck utility 
        Vendor: 
        License: GPL
        Files: 184
        Size(Kb): 1408
        Dependencies: functions >= 1.01.12
healthcheck:
        Version: 1.01.00
        Description: Healthcheck utility 
        Vendor: 
        License: GPL
        Files: 184
        Size(Kb): 1408
        Dependencies: functions >= 1.02.00
.TE

The final example shows use of the "-o files" option to show the list 
of files that are installed as part of a package:

.TS
l.
$ tplist -p functions -o files
.TE

The output generated is as follows (truncated for save space):

.TS
l.
Package: functions,1.02.00,HP-UX,9000800
Rootdir: /home/sedwards/install
/etc/env/010_generic_functions.env
/opt/tools/generic_functions/ksh/check_procs
/opt/tools/generic_functions/ksh/file_modtime
/opt/tools/generic_functions/ksh/format_seconds
/opt/tools/generic_functions/ksh/offset_date
.TE

Notice that the actual installation path for each file can be found by
prefixing the "Rootdir:" value (shown at the top of the output), to
the actual path given.

.SH EXIT CODES
The utility makes use of the following exit codes:

.TP 4
.B 0
The required package listing has been generated successfully.
.TP
.B 1
Invalid command line arguments have been specified - a usage message will
have been shown on standard errror.
.TP
.B 10
A non-zeo return code was generated by the "preremove" script and the force
flag (\fB-f\fP) was not specified.

.SH FILES
When examining information from an installed package database the following
files for each package are referenced:

.TP 8
.B rootdir
Contains the root directory that was used for the package installation.
.TP
.B status
The state of the installed file, which can be committed, installed, broken,
removed or removing.
.TP
.B spec
The package specification file which contains other information about the
package, such as the vendor and license type.
.TP
.B cksums
This file contains a list of all the installed files - it is referenced
if a file level output is required.

.SH SEE ALSO
.BR tpbundle(1M),
.BR tpchk(1M),
.BR tpinstall(1M),
.BR tpintro(1M),
.BR tppkg(1M),
.BR tpremove(1M).

.SH WARRANTY/LICENSE/ENVIRONMENT
This utility is available under the GNU GPL, and comes with 
\fIno warranty or guarantee of any kind\fP.

This program is only suitable for environments that have the following
software components installed:

.TP 4
.B Shell Utilities
The following utilities are required, \fIawk(1)\fP, \fIksh(1)\fP
as well as the standard utiltiies to check, move and remove files and 
directories.
.TP
.B Perl
Any version of Perl from 4 onwards with standard installation libraries
should be suitable. Currently Perl is only used spareingly, but still must
be available.

